home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / f90 / intro_libm.z / intro_libm
Encoding:
Text File  |  2002-10-03  |  12.0 KB  |  242 lines
  1. INTRO_LIBM(3I)                                        Last changed: 4-13-99
  2.  
  3.  
  4. NNAAMMEE
  5.      IINNTTRROO__LLIIBBMM - Introduction to math library routines
  6.  
  7. IIMMPPLLEEMMEENNTTAATTIIOONN
  8.      UNICOS, UNICOS/mk, and IRIX systems
  9.  
  10.      CF90, MIPSpro 7 Fortran 90, MIPSpro Fortran 77
  11.  
  12. DDEESSCCRRIIPPTTIIOONN
  13.      The math routines are listed with the other intrinsic procedures in
  14.      alphabetical order, usually by generic function name.  Generic
  15.      function names are function calls that cause the compiler to compile
  16.      automatically the appropriate data type version of a routine, based on
  17.      the type of the input data.  For example, a call to the generic
  18.      function LLOOGG with a type of input data of complex compiles as CCLLOOGG.
  19.  
  20.      In general, on UNICOS systems, real functions have no prefix; integer
  21.      functions are prefixed with I, double precision functions are prefixed
  22.      with D, complex functions are prefixed with C, and double precision
  23.      complex functions are prefixed with CD (for example, AABBSS, IIAABBSS, DDAABBSS,
  24.      CCAABBSS, and CCDDAABBSS).  Functions with a type different from their
  25.      arguments are noted.  Real functions are usually the same as the
  26.      generic function name.
  27.  
  28.      On UNICOS/mk systems, two precisions are provided for real data:
  29.      32-bit or half precision real and 64-bit or single precision real.
  30.      The specific names for single precision real data provide a link to
  31.      the 64-bit intrinsic functions.  To ensure a link to the 32-bit
  32.      intrinsic functions, use the generic function names with 32-bit real
  33.      arguments.  For example, use LLOOGG for any of the types of real data.
  34.      Use AALLOOGG for single precision real arguments.  Extended precision
  35.      routines of math library routines are not provided on UNICOS/mk
  36.      systems and only some routines have vector versions.
  37.  
  38.      UNICOS/mk systems have an additional library named lliibbmmffaassttvv.  It
  39.      contains versions of selected math intrinsics which can be faster than
  40.      those in the default Math library.  These alternate versions are not
  41.      as accurate as the default library, and in some cases there are
  42.      argument restrictions, such as not allowing the use of infinities.
  43.      These alternate versions are generally faster for loops with 50 or
  44.      more iterations.  To use lliibbmmffaassttvv, use the --ll mmffaassttvv option on the
  45.      compiler's command line to load the library file.  You must compile
  46.      your code with the --OO33 or --OOvveeccttoorr33 option for the Fortran compiler or
  47.      use --hh vveeccttoorr33 with the C compiler.
  48.  
  49.      For information on inlining and vectorization of the Fortran 95
  50.      intrinsic procedures, see IINNTTRROO__IINNTTRRIINN(3I).
  51.  
  52.      For more information on calling library routines from various
  53.      programming languages, see the subsection on this man page titled
  54.      "Calling Functions from Fortran, C, or CAL."
  55.  
  56.      The math routines can be divided into the following general
  57.      categories:
  58.  
  59.      * General arithmetic functions - In the routine descriptions, complex
  60.        arguments are represented as
  61.  
  62.        _x = _x  + _i_x .
  63.             _r     _i
  64.        The real part of the complex number is _x ; _x  is the imaginary part.
  65.                                                _r   _i
  66.        Arguments and results are of the same type unless otherwise
  67.        indicated.
  68.  
  69.        Base values raised to a power and 64-bit integer division are called
  70.        implicitly from Fortran.
  71.  
  72.      * Exponential and logarithmic functions - The UNICOS and UNICOS/mk
  73.        exponential and logarithmic functions are similar to the ANSI
  74.        standard functions.  Each function has variations for real, double
  75.        precision, and complex values except the common logarithm function,
  76.        which addresses only real and double-precision values.  Complex
  77.        arguments are represented as
  78.  
  79.        _x = _x  + _i_x .
  80.             _r     _i
  81.        _x  is the real part of the complex number; _x  is the imaginary part.
  82.         _r                                          _i
  83.      * Trigonometric functions - The trigonometric functions are based on
  84.        the ANSI standard for Fortran, except for the cotangent function and
  85.        the CCOOSSSS (cosine and sine) function, which are extensions.
  86.  
  87.      * Type conversion functions - Type conversion functions change the
  88.        type of an argument.  In the routine description, complex arguments
  89.        are represented as
  90.  
  91.        _x = _x  + _i_x .
  92.             _r     _i
  93.        _x  is the real part of the complex number; _x  is the imaginary part.
  94.         _r                                          _i
  95.        Arguments and results are of the same type, unless indicated
  96.        otherwise.
  97.  
  98.      * Special functions - The special functions provide Fortran access to
  99.        a number of Standard C functions on UNICOS/mk and UNICOS systems.
  100.  
  101.      * Extended-precision routines - The extended-precision routines
  102.        perform double- and triple-precision arithmetic on UNICOS systems.
  103.  
  104.      * Boolean functions - The Boolean functions perform logical operations
  105.        and bit manipulations.  On UNICOS systems, the scalar subprograms
  106.        are external versions of Fortran inline functions.  They are all
  107.        called by address; results are returned in register S1.  All Boolean
  108.        functions are extensions.  These functions cannot be passed as
  109.        arguments with CF90 on any system.
  110.  
  111.    CCaalllliinngg FFuunnccttiioonnss ffrroomm FFoorrttrraann,, CC,, oorr CCAALL
  112.      Because of differences in the calling sequences for these languages,
  113.      and other language differences, important variations must be noted in
  114.      what functions can be called and how they are called.
  115.  
  116.      CCaalllliinngg ffrroomm FFoorrttrraann pprrooggrraammss
  117.      Some function names are in uppercase, and some are in lowercase.  The
  118.      Fortran language is case-insensitive; the UNICOS and UNICOS/mk Fortran
  119.      compilers map all code into uppercase.  This means that functions with
  120.      lowercase names cannot be called from Fortran programs.
  121.  
  122.      CCaalllliinngg ffrroomm CC pprrooggrraammss
  123.      The C language is case sensitive.  You must use the exact case
  124.      specified in the documentation when coding references to a function.
  125.  
  126.      All functions documented in this manual are callable from C programs.
  127.      The following rules can be used:
  128.  
  129.      * Because the function is not declared in a Standard C header,
  130.        explicitly declare the function as external, and specify the type of
  131.        the return value.
  132.  
  133.      * When calling the function, pass the address of the arguments by
  134.        using the address operator (&) for each argument or by using a
  135.        pointer to the argument.  Array names are considered to be
  136.        addresses; the address operator is not needed when using them.
  137.  
  138.      * The value returned by the function is the value, rather than the
  139.        address of the value.
  140.  
  141.      * Specify the ffoorrttrraann keyword.  The ffoorrttrraann keyword is an extension to
  142.        the C language and is useful when a C program calls a function
  143.        following the Fortran calling sequence.  Specifying the ffoorrttrraann
  144.        keyword causes the C compiler to verify that the arguments used in
  145.        each call to the function are pass-by-address.
  146.  
  147.      CCaalllliinngg ffrroomm CCrraayy AAsssseemmbbllyy LLaanngguuaaggee ((CCAALL))
  148.      External references from CAL are case-sensitive, so you must use the
  149.      exact name for functions as specified on the man pages.  Two standard
  150.      calling methods are supported for math functions:  call-by-register
  151.      and call-by-address.  For more information on the details of calling
  152.      sequences, see the documentation for the CCAALLLL macro in _U_N_I_C_O_S _M_a_c_r_o_s
  153.      _a_n_d _O_p_d_e_f_s _R_e_f_e_r_e_n_c_e _M_a_n_u_a_l.
  154.  
  155.      It is strongly recommended that function linkage be done using the
  156.      CCAALLLL macros.  Direct user calls to functions by using the return-jump
  157.      instruction should be avoided.
  158.  
  159.      Scalar functions return the result in registers S1 (and S2 if needed);
  160.      results for complex double precision are returned in S1 through S4.
  161.      Vector functions return their result in registers V1 (and V2 if
  162.      needed); complex double precision are returned in V1 through V4.  The
  163.      number of elements computed for vector functions is determined by the
  164.      contents of the vector-length register (VL) upon entry.
  165.  
  166.      For example, to call the SSQQRRTT routine using the call-by-address
  167.      sequence, let _a_r_g_1 be the address of the argument.
  168.  
  169.      CAL usage:
  170.  
  171.      EEXXTT     SSQQRRTT          Declare the name to be an external
  172.      CCAALLLL    SSQQRRTT,,((_a_r_g_1)   Call the function
  173.      (result)S1            The result is returned in register S1 and
  174.                            stored at the address result
  175.  
  176.      Note that the name SSQQRRTT must be uppercase.
  177.  
  178.      To call the SSQQRRTT routine by using the call-by-register convention:
  179.  
  180.      (S1) Value of the argument
  181.  
  182.      CAL usage:
  183.  
  184.      EEXXTT     SSQQRRTT%%         Declare the name to be an external
  185.      CCAALLLLVV   SSQQRRTT%%         Call the function
  186.      (result)S1            The result is returned in register S1 and
  187.                            stored at the address result
  188.  
  189.      To call the routine for vector SSQQRRTT using the call-by-register
  190.      convention, let V1 be the value of the vector argument and VL be the
  191.      vector length (between 1 and 64 values will be returned).
  192.  
  193.      CAL usage:
  194.  
  195.      EEXXTT     %%SSQQRRTT%%        Declare the name to be an
  196.                            external
  197.      CCAALLLLVV   %%SSQQRRTT%%        Call the function
  198.  
  199.      The result is returned in register V1.  The vector-length register VL
  200.      is unchanged.
  201.  
  202.      NNaammiinngg ccoonnvveennttiioonnss
  203.      Most of the UNICOS math library functions adhere to the following
  204.      naming convention:
  205.  
  206.      NNAAMMEE        Entry for call-by-address
  207.  
  208.      NNAAMMEE%%       Entry for scalar call-by-register
  209.  
  210.      %%NNAAMMEE%%      Entry for vector call-by-register
  211.  
  212.      Note that assembly language does not support generic function names or
  213.      automatic data type conversion.  For example, there is no math library
  214.      LLOOGG function for the logarithm routine.  You must specify either AALLOOGG,
  215.      DDLLOOGG, or CCLLOOGG for real, double-precision, or complex logarithm
  216.      respectively, and the argument must be of the correct type (real,
  217.      double-precision, or complex).
  218.  
  219.      RReeggiisstteerr ccoonnvveennttiioonnss
  220.      By default, all the UNICOS and UNICOS/mk Fortran compilers use the
  221.      call-by-register convention for math library functions (it is the
  222.      fastest calling sequence), and will put the %% prefix or suffix on the
  223.      function name where needed.  If a math library function is declared
  224.      EEXXTTEERRNNAALL or IINNTTRRIINNSSIICC, the compilers will generate code for the call-
  225.      by-address method.
  226.  
  227. SSEEEE AALLSSOO
  228.      IINNTTRROO__IINNTTRRIINN(3I)
  229.  
  230.      _C_r_a_y _S_t_a_n_d_a_r_d _C _R_e_f_e_r_e_n_c_e _M_a_n_u_a_l
  231.  
  232.      _C_F_9_0 _C_o_m_m_a_n_d_s _a_n_d _D_i_r_e_c_t_i_v_e_s _R_e_f_e_r_e_n_c_e _M_a_n_u_a_l
  233.  
  234.      _F_o_r_t_r_a_n _L_a_n_g_u_a_g_e _R_e_f_e_r_e_n_c_e _M_a_n_u_a_l, _V_o_l_u_m_e _1
  235.  
  236.      _F_o_r_t_r_a_n _L_a_n_g_u_a_g_e _R_e_f_e_r_e_n_c_e _M_a_n_u_a_l, _V_o_l_u_m_e _2
  237.  
  238.      _F_o_r_t_r_a_n _L_a_n_g_u_a_g_e _R_e_f_e_r_e_n_c_e _M_a_n_u_a_l, _V_o_l_u_m_e _3
  239.  
  240.      _I_n_t_r_i_n_s_i_c _P_r_o_c_e_d_u_r_e_s _R_e_f_e_r_e_n_c_e _M_a_n_u_a_l for the printed version of this
  241.      man page.
  242.